[<<Previous Entry]
[^^Up^^]
[Next Entry>>]
[Menu]
[About The Guide]
spawnle() Execute Program Using Argument List and Environment
#include <process.h>
int spawnle(modeflag,pathname,arg0,arg1,...,argn,NULL,envp);
int modeflag; Execution mode for parent process
char *pathname; Path name of file to be executed
char *arg0,*arg1,...,*argn; List of pointers to argument
char *envp[]; Array of pointers to environment
settings
spawnle() loads and executes a new child process. 'modeflag'
determines whether the parent process is overlaid in memory or waits
for the new process to be completed. 'modeflag' should be set to one
of the following values (defined in <process.h>):
P_WAIT Wait for child process to finish.
P_OVERLAY Child process overlays the area in memory occupied by
parent process. This is equivalent to using the
execl() function.
P_NOWAIT, executes the parent process concurrently with the
child. This, however, is not currently implemented
and returns an error value.
'pathname' specifies the path and file name of the child process. If
'pathname' includes a file name extension, only that file is searched
for. If 'pathname' ends with a period (.), then 'pathname' without an
extension is searched for. If 'pathname' has no extension and does
not end with a period, then spawnle() searches for 'pathname'; if
'pathname' is not found, the extension .COM is appended and the
search is repeated. If that is not found, .EXE is appended and the
search is repeated.
'arg0', 'arg1',...'argn' are passed to the child process as command-
line parameters. A NULL pointer must follow 'argn' to terminate the
list of arguments. 'arg0' must not be NULL; it is usually set to
'pathname'.
The combined length of all the arguments passed to the child process
must not exceed 128 bytes. This includes "n" (for 0-n arguments)
space characters (required to separate the arguments), but does not
include the null ('\0') terminating character.
'envp' points to an array of pointers that, in turn, point to strings
that define environment variables. These strings usually have the
form ENVVAR=value; "ENVVAR" is the name of the variable and "value'
is the string value to which it is set. The 'envp' array is
terminated by a NULL pointer. If 'envp' is NULL, the child process
acquires the environment of the calling process.
Returns: All spawn functions return the exit status of the
child process. The exit status is 0 if the process
terminated normally. The child process can set the
exit status to a nonzero value by calling exit() with
the desired return value.
If not set by the child process, a positive exit
status indicates an error by an abort() or an
interrupt.
A return value of -1 indicates an error, and 'errno'
is set to one of the following:
E2BIG Argument list or environment list too big
(List > 128 bytes, or environment > 32k)
EINVAL Invalid 'modeflag' argument
ENOENT File or path not found
ENOEXEC File not executable
ENOMEM Not enough memory
A child process spawned with 'modeflag' set to
P_OVERLAY does not return to the calling process.
Notes: Any file that is open when a spawn call is made
remains open in the child process. This includes
'stdin','stdout', 'stderr', 'stdaux', and 'stdprn'.
spawnle() does not preserve the translation modes of
open files. Use setmode() in the child process to
set the desired translation modes.
Signal settings (see ssignal()) are not preserved.
They are reset to the default in the child process.
Portability: MS-DOS only.
-------------------------------- Example ---------------------------------
The following statements transfer execution to the child process
"child.exe" and pass it the three arguments "child", "arg1", and
"arg2". The PATH environment variable is set to "C:\TEST" for the
child process. The exit status of the child is printed upon return.
#include <process.h> /* for 'spawnle' and 'P_WAIT' */
#include <stdio.h> /* for 'printf' and 'NULL' */
#include <errno.h> /* for 'errno','ENOENT' and 'ENOMEM' */
char *env[] = {"PATH=C:\\TEST", NULL};
main()
{
int result;
result = spawnle(P_WAIT,"child.exe",
"child","arg1","arg2",NULL, env);
if (result != -1)
printf("exit status of child.exe = %d\n", result);
else {
if (errno == ENOENT)
printf("child.exe not found in current directory\n");
else if (errno == ENOMEM)
printf("not enough memory to execute child.exe\n");
else
printf("error #%d trying to spawn child.exe\n",
errno);
}
}
See Also:
spawn...()
exec...()
This page created by ng2html v1.05, the Norton guide to HTML conversion utility.
Written by Dave Pearson